Summary

Fixes a filesystem + token-leak bug (#221) where three per-job paths under CLONE_BASE_DIR were orphaned after a pod SIGKILL, OOM kill, or spot eviction: the clone directory <workDir>, the installation-token-bearing credential helper <workDir>.cred.sh, and the sibling summary directory <workDir>-artifacts. Two independent gaps combined: registerExitCleanup and handleJobCancel in job-executor.ts removed only the clone dir + credential helper (the -artifacts dir was always leaked, even on graceful exit), and the daemon had no startup sweep at all — the only reaper lived in app.ts, ran in the webhook/orchestrator process (wrong filesystem in production), and was scoped to *.cred.sh files only.

Flow

flowchart TD
    Kill["SIGKILL or OOM or eviction<br/>also graceful exit and cancel"]:::trig
    Old["Before<br/>exit and cancel removed clone dir and cred.sh only<br/>app.ts reaper removed cred.sh only"]:::old
    Leak["Orphaned<br/>-artifacts dir always<br/>clone dir on daemon SIGKILL"]:::old
    New["After<br/>removeWorkspaceTripleSync removes all three<br/>on exit and cancel"]:::new
    Sweep["sweepStaleWorkspaces at startup<br/>reaps entries older than WORKSPACE_STALE_TTL_MS<br/>emits a workspace.sweep log line"]:::new
    Clean["No orphans accumulate"]:::keep
    Kill --> Old --> Leak
    Kill --> New --> Clean
    Sweep --> Clean
    classDef trig fill:#1f618d,color:#ffffff
    classDef old fill:#7b2d2d,color:#ffffff
    classDef new fill:#2c5f2e,color:#ffffff
    classDef keep fill:#2c3e50,color:#ffffff

Changes

• New src/core/workspace-sweep.ts (parameter-based, config-free):
  • removeWorkspaceTripleSync(workDir) — synchronous best-effort removal of the full triple, for process.on("exit") / cancel handlers; self-guards the empty-workDir scoped-job invariant so no removal can target a CWD-relative .cred.sh/-artifacts.
  • sweepStaleWorkspaces(cloneBaseDir, ttlMs, log) — async TTL reaper; tolerant of a missing base dir and concurrent removal; emits one structured workspace.sweep log line with {swept, retained, durationMs}.
• src/daemon/job-executor.ts — both registerExitCleanup and handleJobCancel now call removeWorkspaceTripleSync (the -artifacts sibling is now reaped on crash exit and cancel). Scoped-job guards (workDir === "") preserved.
• src/daemon/main.ts — sweepStaleWorkspaces runs once at boot, before discoverCapabilities and the WebSocket connect, so no in-flight job of this lifetime can be reaped.
• src/app.ts — the inline *.cred.sh-only reaper is replaced by the shared helper (now also sweeps clone dirs + artifacts); dead STALE_CRED_TTL_MS constant and now-unused imports removed.
• src/config.ts — new workspaceStaleTtlMs from WORKSPACE_STALE_TTL_MS (default 3600000 = 1h, positive-int validated).
• Docs — configuration.md (env row), observability.md (workspace.sweep event), runbooks/daemon-fleet.md (startup sweep).
• Tests — test/core/workspace-sweep.test.ts: triple removal, absent-path no-op, empty-workDir no-op, aged-swept/fresh-retained (exact counts + workspace.sweep log assertion), partial-orphan stale-cred.sh independence, missing-base tolerance.

Why it's safe

cloneBaseDir is pod-local ephemeral storage (no shared volume in the ephemeral-daemon Pod spec) holding only ephemeral per-job workspaces — every job mkdtemps fresh; there is no persistent repo cache. The sweep runs at startup before any job is accepted, so the mtime-based per-entry reap cannot touch a live workspace.

Related issues

Closes #221

Test plan

• test/core/workspace-sweep.test.ts — 6 cases, all pass in isolation
• typecheck / lint / format / docs:build (mkdocs strict + doc-sync + citations) clean
• Full bun test: stash-verified baseline shows this change adds passes with fail/error counts unchanged; remaining failures are pre-existing local DB/Valkey-absent suites. The isolated CI runner (scripts/test-isolated.sh) is the authoritative signal.